home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / idl / nsIWebBrowser.idl < prev    next >
Text File  |  2006-05-08  |  7KB  |  171 lines
  1. /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  2.  *
  3.  * ***** BEGIN LICENSE BLOCK *****
  4.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  5.  *
  6.  * The contents of this file are subject to the Mozilla Public License Version
  7.  * 1.1 (the "License"); you may not use this file except in compliance with
  8.  * the License. You may obtain a copy of the License at
  9.  * http://www.mozilla.org/MPL/
  10.  *
  11.  * Software distributed under the License is distributed on an "AS IS" basis,
  12.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13.  * for the specific language governing rights and limitations under the
  14.  * License.
  15.  *
  16.  * The Original Code is the Mozilla browser.
  17.  *
  18.  * The Initial Developer of the Original Code is
  19.  * Netscape Communications, Inc.
  20.  * Portions created by the Initial Developer are Copyright (C) 1999
  21.  * the Initial Developer. All Rights Reserved.
  22.  *
  23.  * Contributor(s):
  24.  *   Travis Bogard <travis@netscape.com>
  25.  *
  26.  * Alternatively, the contents of this file may be used under the terms of
  27.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  28.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29.  * in which case the provisions of the GPL or the LGPL are applicable instead
  30.  * of those above. If you wish to allow use of your version of this file only
  31.  * under the terms of either the GPL or the LGPL, and not to allow others to
  32.  * use your version of this file under the terms of the MPL, indicate your
  33.  * decision by deleting the provisions above and replace them with the notice
  34.  * and other provisions required by the GPL or the LGPL. If you do not delete
  35.  * the provisions above, a recipient may use your version of this file under
  36.  * the terms of any one of the MPL, the GPL or the LGPL.
  37.  *
  38.  * ***** END LICENSE BLOCK ***** */
  39.  
  40. #include "nsISupports.idl"
  41.  
  42. interface nsIInterfaceRequestor;
  43. interface nsIWebBrowserChrome;
  44. interface nsIURIContentListener;
  45. interface nsIDOMWindow;
  46. interface nsIWeakReference;
  47.  
  48. /**
  49.  * The nsIWebBrowser interface is implemented by web browser objects.
  50.  * Embedders use this interface during initialisation to associate
  51.  * the new web browser instance with the embedders chrome and
  52.  * to register any listeners. The interface may also be used at runtime
  53.  * to obtain the content DOM window and from that the rest of the DOM.
  54.  *
  55.  * @status FROZEN
  56.  */
  57. [scriptable, uuid(69E5DF00-7B8B-11d3-AF61-00A024FFC08C)]
  58. interface nsIWebBrowser : nsISupports
  59. {
  60.     /**
  61.      * Registers a listener of the type specified by the iid to receive
  62.      * callbacks. The browser stores a weak reference to the listener
  63.      * to avoid any circular dependencies.
  64.      * Typically this method will be called to register an object
  65.      * to receive <CODE>nsIWebProgressListener</CODE> or 
  66.      * <CODE>nsISHistoryListener</CODE> notifications in which case the
  67.      * the IID is that of the interface.
  68.      *
  69.      * @param aListener The listener to be added.
  70.      * @param aIID      The IID of the interface that will be called
  71.      *                  on the listener as appropriate.
  72.      * @return          <CODE>NS_OK</CODE> for successful registration;
  73.      *                  <CODE>NS_ERROR_INVALID_ARG</CODE> if aIID is not
  74.      *                  supposed to be registered using this method;
  75.      *                  <CODE>NS_ERROR_FAILURE</CODE> either aListener did not
  76.      *                  expose the interface specified by the IID, or some
  77.      *                  other internal error occurred.
  78.      *
  79.      * @see removeWebBrowserListener
  80.      * @see nsIWeakReference
  81.      * @see nsIWebProgressListener
  82.      * @see nsISHistoryListener
  83.      *
  84.      * @return <CODE>NS_OK</CODE>, listener was successfully added;
  85.      *         <CODE>NS_ERROR_INVALID_ARG</CODE>, one of the arguments was
  86.      *         invalid or the object did not implement the interface
  87.      *         specified by the IID.
  88.      */
  89.     void addWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);
  90.  
  91.     /**
  92.      * Removes a previously registered listener.
  93.      *
  94.      * @param aListener The listener to be removed.
  95.      * @param aIID      The IID of the interface on the listener that will
  96.      *                  no longer be called.
  97.      *
  98.      * @return <CODE>NS_OK</CODE>, listener was successfully removed;
  99.      *         <CODE>NS_ERROR_INVALID_ARG</CODE> arguments was invalid or
  100.      *         the object did not implement the interface specified by the IID.
  101.      *
  102.      * @see addWebBrowserListener
  103.      * @see nsIWeakReference
  104.      */
  105.     void removeWebBrowserListener(in nsIWeakReference aListener, in nsIIDRef aIID);
  106.  
  107.     /**
  108.      * The chrome object associated with the browser instance. The embedder
  109.      * must create one chrome object for <I>each</I> browser object
  110.      * that is instantiated. The embedder must associate the two by setting
  111.      * this property to point to the chrome object before creating the browser
  112.      * window via the browser's <CODE>nsIBaseWindow</CODE> interface. 
  113.      *
  114.      * The chrome object must also implement <CODE>nsIEmbeddingSiteWindow</CODE>.
  115.      *
  116.      * The chrome may optionally implement <CODE>nsIInterfaceRequestor</CODE>,
  117.      * <CODE>nsIWebBrowserChromeFocus</CODE>,
  118.      * <CODE>nsIContextMenuListener</CODE> and
  119.      * <CODE>nsITooltipListener</CODE> to receive additional notifications
  120.      * from the browser object.
  121.      *
  122.      * The chrome object may optionally implement <CODE>nsIWebProgressListener</CODE> 
  123.      * instead of explicitly calling <CODE>addWebBrowserListener</CODE> and
  124.      * <CODE>removeWebBrowserListener</CODE> to register a progress listener
  125.      * object. If the implementation does this, it must also implement
  126.      * <CODE>nsIWeakReference</CODE>.
  127.      * 
  128.      * @note The implementation should not refcount the supplied chrome
  129.      *       object; it should assume that a non <CODE>nsnull</CODE> value is
  130.      *       always valid. The embedder must explicitly set this value back
  131.      *       to nsnull if the chrome object is destroyed before the browser
  132.      *       object.
  133.      *
  134.      * @see nsIBaseWindow
  135.      * @see nsIWebBrowserChrome
  136.      * @see nsIEmbeddingSiteWindow
  137.      * @see nsIInterfaceRequestor
  138.      * @see nsIWebBrowserChromeFocus
  139.      * @see nsIContextMenuListener
  140.      * @see nsITooltipListener
  141.      * @see nsIWeakReference
  142.      * @see nsIWebProgressListener
  143.      */
  144.     attribute nsIWebBrowserChrome containerWindow;
  145.  
  146.     /**
  147.      * URI content listener parent. The embedder may set this property to
  148.      * their own implementation if they intend to override or prevent
  149.      * how certain kinds of content are loaded.
  150.      *
  151.      * @note If this attribute is set to an object that implements
  152.      *       nsISupportsWeakReference, the implementation should get the
  153.      *       nsIWeakReference and hold that.  Otherwise, the implementation
  154.      *       should not refcount this interface; it should assume that a non
  155.      *       null value is always valid.  In that case, the embedder should
  156.      *       explicitly set this value back to null if the parent content
  157.      *       listener is destroyed before the browser object.
  158.      *
  159.      * @see nsIURIContentListener
  160.      */
  161.     attribute nsIURIContentListener parentURIContentListener;
  162.  
  163.     /**
  164.      * The top-level DOM window. The embedder may walk the entire
  165.      * DOM starting from this value.
  166.      *
  167.      * @see nsIDOMWindow
  168.      */
  169.     readonly attribute nsIDOMWindow contentDOMWindow;
  170. };
  171.